/**
 * ***************************************************************************** Copyright (c) 2008,
 * 2010 Freescale Semiconductor and others. All rights reserved. This program and the accompanying
 * materials are made available under the terms of the Eclipse Public License v1.0 which accompanies
 * this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html
 *
 * <p>Contributors: Serge Beauchamp (Freescale Semiconductor) - initial API and implementation IBM -
 * ongoing development *****************************************************************************
 */
package org.eclipse.core.resources;

import org.eclipse.core.runtime.*;

/**
 * A description of a resource filter.
 *
 * <p>A filter determines which file system objects will be visible when a local refresh is
 * performed for an IContainer.
 *
 * @see IContainer#getFilters()
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 * @since 3.6
 */
public interface IResourceFilterDescription {

  /*====================================================================
   * Constants defining which members are wanted:
   *====================================================================*/

  /**
   * Flag for resource filters indicating that the filter list includes only the files matching the
   * filters. All INCLUDE_ONLY filters are applied to the resource list with an logical OR
   * operation.
   */
  public static final int INCLUDE_ONLY = 1;

  /**
   * Flag for resource filters indicating that the filter list excludes all the files matching the
   * filters. All EXCLUDE_ALL filters are applied to the resource list with an logical AND
   * operation.
   */
  public static final int EXCLUDE_ALL = 2;

  /** Flag for resource filters indicating that this filter applies to files. */
  public static final int FILES = 4;

  /** Flag for resource filters indicating that this filter applies to folders. */
  public static final int FOLDERS = 8;

  /**
   * Flag for resource filters indicating that the container children of the path inherit from this
   * filter as well.
   */
  public static final int INHERITABLE = 16;

  /**
   * Returns the description of the file info matcher corresponding to this resource filter.
   *
   * @return the file info matcher description for this resource filter
   */
  public FileInfoMatcherDescription getFileInfoMatcherDescription();

  /**
   * Return the resource towards which this filter is set.
   *
   * @return the resource towards which this filter is set
   */
  public IResource getResource();

  /**
   * Return the filter type, either INCLUDE_ONLY or EXCLUDE_ALL
   *
   * @return (INCLUDE_ONLY or EXCLUDE_ALL) and/or INHERITABLE
   */
  public int getType();

  /**
   * Deletes this filter description from its associated resource.
   *
   * <p>The {@link IResource#BACKGROUND_REFRESH} update flag controls when changes to the resource
   * hierarchy under this container resulting from the filter removal take effect. If this flag is
   * specified, the resource hierarchy is updated in a separate thread after this method returns. If
   * the flag is not specified, any resource changes resulting from the filter removal will occur
   * before this method returns.
   *
   * <p>This operation changes resources; these changes will be reported in a subsequent resource
   * change event that will include an indication of any resources that have been added as a result
   * of the filter removal.
   *
   * <p>This operation is long-running; progress and cancellation are provided by the given progress
   * monitor.
   *
   * @param updateFlags bit-wise or of update flag constants ({@link IResource#BACKGROUND_REFRESH})
   * @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
   * @exception CoreException if this filter could not be removed. Reasons include:
   *     <ul>
   *       <li>Resource changes are disallowed during certain types of resource change event
   *           notification. See <code>IResourceChangeEvent</code> for more details.
   *     </ul>
   *
   * @exception OperationCanceledException if the operation is canceled. Cancelation can occur even
   *     if no progress monitor is provided.
   * @see IContainer#getFilters()
   * @see IContainer#createFilter(int, FileInfoMatcherDescription, int, IProgressMonitor)
   */
  public void delete(int updateFlags, IProgressMonitor monitor) throws CoreException;
}
